iDIOT Compiler (beta v2) (man revi)
Naspite Labs (C) 2017

1.  WHAT IS IDIOT COMPILER
2.  WHAT IDIOT COMPILER IS NOT
3.  TAKE AN EXAMPLE... why/how its different
4.  VARIABLES VS NUMBERS
5.  SETUP program
6.  COMMANDS CURRENTLY IMPLIMENTED...
7.  How LET works... Simple Math
8.  WORKING ON MORE THINGS
9.  PITFALLS
10. LINENUMBER INFO
11. FOR NEXT LOOPS...


**(SEE #9, #10 and #11 for LINENUMBER INFO before starting...)**


1.  What is Idiot Compiler....

	This compiler has taken a different approach to creating files than other established
Applesoft Compilers.  TASC, BEAGLE and Einstein Hayden Compilers are fully compatible with
Applesoft, and process entire applesoft programs, as a large chunk.  They also contain RUNTIMES
either external like TASC and Hayden, or internally like Einstein.  These RUNTIMES bloat file
sizes by containing a large number of subroutines that do a host of functions, but usually
not every routine is needed.  It is great for compatibility, and potentialy does lower file sizes
for VERY LARGE compiled programs.  

	The major downside of RUNTIMES is speed.  Compilers usually do nothing more than setting
up partial subroutine values and then JSR'ing to a routine that only does a small part of the
final output... to make a simple APPLESOFT routine function requires several JSR's and is very
inefficient.  In comparison, an Assembly programmer goes to the heart of the matter and deals with
the problem directly and efficiently, using only variables required to do the task at hand.  This is
the approach of Idiot Compiler... and creates code very similar to what an Assembly programmer would
create without the overhead of cumbersom setup routines to obscure RUNTIME code.  In fact, the actual
compiled code can be read by an assembly programmer and pretty much understood with little difficulty.
Try doing that with something like Microsoft's TASC.

2.  What IDIOT COMPILER is not...

	It is a very simple compiler.  There are many things it can not currently do, and will never do.
If you want an ALL-IN-ONE solution, the commerical compilers are a better overall package and almost
hassle free.
	It Does Not Do COMPLEX MATH, NEGATIVE NUMBERS, STRING VARIABLES, and its INPUTS are similar
	to APPLESOFT like statements, but do not confuse that with total compatibility.  There are many
	decisions taken to make code INCREDIBLY FAST compared to the other compilers... but functionality
	is limited.


3.  Take an example... with 16 bit math enabled...
	If you wanted A = B + C.... Idiot Compiler will employ 16 bit math, which is only a couple of
instructions at most.   In comparison to other compilers... they require access to full floating point
math, with 40bit mathematics.  Idiot directly loads numbers/variables in A,B & C and adds them, placing 
results directly into variable locations... other compilers load each variable and dumps them into
generic formulations from the RUNTIME, and often the setup is just about the same number of clock cycles
as the actual calculation is.. huge inefficiences.  The result is 4 to 8 times more time to process the
equation than an Assembly coder would do if directly.  Idiot Compiler is VERY CLOSE to the minimum required,
that speed is negilable between the two...


===============================================
** (THIS IS THE FIRST RELEASE VERSION - feedback and ideas for future compatibility and features is
greatly appreciated ) **
===============================================


4.  VARIABLES VRS #NUMBERS


(Note to users of previous betas... ** CAUTION ** you NO LONGER need the # sign for number input...

	Whenever you see a prompt, such as  (VAR OR #XX), the prompt may change, allowing only a
	variable or a number entry.  (VAR OR #XX) ... (VAR     ) ....(      #XX)  

	To enter a number... just enter the number.  If you enter any weird charrecters other than
	numbers, it will automatically assume its a variable.. even if it has $ or # in the 'string'.
	** Be cautious of limitation values in the data you are entering... for example, if entering
	an 8 bit number... if your typed value is larger than 255... you may loose or have incorrect data.

	To enter a variable... type the variable name. It can be named any length of normal charrecters,
	so pretty much anything you want to call it... even a string including numbers are acceptable!!!



5.  SETUP

	Before creating your compiled program... type RESET.  This will clear a host of things, including
	     1.  VARIABLES
	     2.  LINE NUMBERS
	     3.  FOR NEXT LOOP COUNTERS
	     4.  MOST LINE NUMBERS - (there may be sistuations where some line number files may not be deleted).

	The only thing you need to worry about is how many [FOR NEXT LOOPS ] 

	- HOW MANY FOR NEXT LOOPS... the compiler uses a clever FOR NEXT loop system with built in variables
	that do not use the stack.... in comparison APPLESOFT uses 16 stack locations for every FOR NEXT
	loop... IDIOT COMPILER uses only 2 memory locations... as you can imagine, the speed increase is
	incredible!  Choose only a couple... most of the time you wont need more than 2 or 3 as when a FOR
	NEXT loop ends, it reclaims the variable space/stack!


6.  COMMANDS IMPLIMENTED (Some may be limited?)

	HOME

	CALL

	TEXT

	INVERSE

	FLASH

	COLOR = (# OR VAR)

	PLOT = X,Y (# OR VAR)

	GR

	RUN (RESETS PROGRAM... BUT NOT VARIABLES)

	VTAB = (# OR VAR)

	HTAB = (# OR VAR)

	PEEK (example...  PEEK INTO VARIABLE)

	POKE (example.... (# OR VAR) INTO LOCATION

	STOP (FORCE PROGRAM TO END PROGRAM EXECUTION- SIMILAR TO "END" IN APPLESOFT)

	SCRN =X,Y (# OR VAR)

	VLIN X,X2,Y (# OR VAR)

	HLIN Y,Y2,X (# OR VAR)

	NORMAL

	GOSUB (GOSUB TO A NAMED LINE)

	GOTO  (GOTO  TO A NAMED LINE)

	RND  (PUTS A RANDOMIZED MAX VALUE INTO VARIABLE)

	LET - MATH STUCTURE (# OR VAR)...LOOK FOR PROMPTS 

	LET8-	8BIT MATH (FASTER THAN 16BIT LET)

	LET24-	HIGHER NUMBER CAPABILITY 24BIT MATH

	IF-  IF VARIABLE = (# OR VAR) THEN IT PASSES THRU ARGUMENT, IF NOT IT (GOTO NEXT LINE)

	FOR-  CREATES A FOR NEXT LOOP FROM #FIRST TO #SECOND  (NO STEP CAPABILITY...
		(FOR NEXT can not be used as a variable...must have external variable that can be
		incremented with statements like  LET A= A + 1 (or whatever...)... this is done for
		speed increases as not every FOR NEXT loop requires to use that variable...

	PRINT- (1.  You can print a STRING) or (2.  You can print the NUMERICAL VALUE of a variable)

	DOS-	CAN BRUN OR BLOAD AN ARGUMENT... DOES NOT NEED PRINT CHR$(4) AND " MARKS... JUST COMMAND.
		THERE ARE BUGS...SOMETHINGS WORK, SOME DONT... CAN NOT CREATE TEXT FILES YET WITH IT...
	
	HGR-	TURNS ON HIGH RESOLUTION GRAPHICS MODE SCREEN

	HCOLOR-	COLOR OF HIRES (0-6) -(# OR VAR)

	HPLOT-	PLOTS CORD AT X,Y  -(# OR VAR)

	-------INTERNAL COMMANDS-----------------
	
	COMPILE-	COMPILES YOUR PROGRAM WITH CURRENT FILES/DATASETS
	QUIT-		EXITS PROGRAM
	RESET-		RESETS ALL PROGRAM FILES, LINE NUMBERS AND VARIABLES
	END-		IF INSIDE A LINE IT ENDS LINE, SAVES DATA TO FILE.
	LINES-		LISTS ALL FILES IN YOUR CURRENT PROGRAM (MAY NOT BE IN ORDER)
	COMMANDS-	SHOWS LIST OF VALID COMMANDS
	HELP-		SHOWS A SIMPLE HELP SCREEN FOR QUICK REFERENCE
	CANCEL-		MOST CASES, CANCELS YOUR CURRENT LINE WITHOUT SAVING
	("JUST"-ENTER)	MOST CASES WILL DROP YOU OUT OF CURRENT INSTRUCTION WITHOUT CODING IT...


7.  How LET works... Simple Math

	If you are familure with Integer Basic... the LET command allows variables to be equal to something.
	In IDIOT COMPILER... LET allows variables to equal numbers, or simple equations.
		For instance...  
			LET  A = B 
				A can equal B (or any other variable)... or A = #number

			LET A=B+C is simple addition.. you dont have to use different variables
				If the desired effect is...   (A = B + C) OR (A = B + #5) OR (A = A + B)

			LET A=B-C is the same as addition.. HOWEVER the only limitation is you can not
				have the result be a negative number... 
			
			LET A=A*B (...A= A*B note that it uses the same argument twice.

			LET A=A/B (must be all variables... A= A/B note that it uses the same argument twice:
				the division only results in whole numbers... not designed for percission...
				just speed.

		LET8 AND LET24
			USING THE STANDARD (LET) COMMAND employs 16bit math.  HOWEVER, if you wish to use
			the commands LET8 and LET24, this allows extra capability to have either LARGER
			number variables (0 thru 16,777,216), or incredibly fast 8bit (0-255) values.
			Functions for these may not be as robust as LET(16) but gives the programmer
			other options.

			**BE CAREFUL USING LET8 AND LET24.... the compiler has no idea what you plan on
			using numbers for inside your program.  Do not mix variables with the different
			math types... you can ADD a 8bit variable to a 16 bit variable, but adding a 16
			bit variable to an 8bit variable and then assuming that variable is still 8 bit
			will result in math errors.  KEEP ALL TYPES SEPERATE unless your really sure
			it will not mess with your desired output values.

		SPECIAL 16BIT QUICKIES
			YOU MAY find an OPTION called 16BIT QUICKES.... this gives you the option to do a 
			small subset of features in far less code and faster speeds than regular generic
			routines... such as INC or DEC a variable by 1, or to DIVIDE a variable by 2.
			These functions speed up your program to BEST HAND-WRITTEN ASSEMBLY SPEED, and
			is encouraged to be used to give the APPLESOFT programmer huge advantages over
			other compilers!  (*more functions to be added in subsequent versions!)

8.  WORKING ON MORE THINGS...
	
	If you need help with IDIOT compiler, contact me at   (TREEHOUSE2000US (AT) YAHOO.COM and i'll write you back,
	or get ahold of me on facebook PM.  I'll do the best I can to help you out.. a few more functions are planned
	in the next week or two that will make it far more useful... or bug fixes, or make easier to use!


9.  PITFALLS...

	YOU MUST DO "RESET" EVERYTIME YOU START A NEW PROJECT... TO CLEAR THE LINES LIST, VARIABLES ECT...
	
	IF YOU ENTER IN INCORRECT COMMANDS, THERE IS NO BACK-FEATURE... so be extremely careful entering data.
	Remember... this is a compiler... not a commandline interpeter or applesoft editor... it is highly
	recommended you make sure your program is finished and bug tested before compiling... also advice for
	any commerical compiler.   *(You can always type CANCEL to cancel a bad line, then restart fresh)

	LINENUMBERS can be ODD... see #10....

	FOR NEXT Loops are a little different than Applesoft... but you stil can do them!  * (See Section 11)*

	*** ENTERING CODE... BE CAUTIOUS OF ENTERING NUMBERS....  Numbers must be fully numeric.  It calculates
	the value of the argument, so if it contains ANY STRING content, it will fail the numeric test and
	automatically call your input a VARIABLE.  If the variable does not exist yet, it will automatically
	create a brand new one for use and add it to the VARIABLE TABLE.  Each VARIABLE takes up 3 bytes of
	memory in your code, so try not to make a whole bunch of unneeded variables.   Variables are dynamicaly
	created and even if you cancel a code line, those variables will still remain in the table.
	   ***  If you do spot an error in the code, type CANCEL... and try typing the line over. **

10.  LINENUMBER INFO
	
	This compiler can only work with LINES 1 thru 999.  Do not create line numbers above 999
	(1000, 1010, 20500 ect...)... for normal execution workflow.

	That being said... there is a caviot to this.  A line number has the potential to be larger than 999
	in special circumstances... those mainly in GOTO , GOSUB inside FOR/NEXT Loops.  These line numbers
	"names" can be just about ANY Length in size.. can be numbers or a word... but they must be longer
	than 3 charrecters... like   GOSUB10 or FRUITIE are accepable names.  These can ONLY be accessed
	by the GOTO, GOSUB and FOR NEXT LOOP commands, they will not execute on their own in the course of
	a normal program.

11.  FOR NEXT LOOPS...

	A FOR NEXT loop is complex thing.  Mentioned above, it takes 16 bytes of STACK for it to exist in
	Applesoft.  What we did here is to limit the FOR NEXT Loop to a 16bit value (maximum of 1 to 65536)
	... and eliminating the STEP capability... such as  FOR A=1 to 65000 STEP 3.... you only have the
	capability to FOR 1 to 65000.   There were also clever tricks to prevent comparisons, so instead
	of counting UP from a number to the max... only the MAXIMUM interation is stored and deincremented
	to a count of ZERO... 

		Also to prevent complication... INSIDE the FOR/NEXT loop, it creates an automatic FORCED
	GOSUB.... so you must enter a name of a FUTURE Line Number that is LONGER than 3 bytes in length,
	but fortunately you can name it a larger number... SUCH 2000, 20000 or even a name like GOOPIE.

	Immediately after the command FORCED GOSUB... the program will pick up right where it left off...
	and you dont even have to END the line number your currently on..  JUST REMEMBER, you must now
	make that LINE NUMBER you named later on in your program, or it will crash durring compiling.

	The OTHER thing about FOR NEXT LOOPS... is you can not use the value of the FOR NEXT loop as a variable.
	In applesoft you can  ( FOR A=1 to 10: PRINT A: NEXT )
	To make things faster, you wont ALWAYS use the FOR NEXT as a variable.. if you desire to do the above...

	FOR  -  #1  -  #10   GOSUB "LINEX"

	"LINEX"    LET A = A+1   - PRINT  A - RTS
	
	You have to make your OWN step code in the LET A = A + 1 or A= A+3 statement, inside the line number  "LINEX".



	






